---------------------------------------------------------
Microsoft Data Link API version 2.0 Readme File
---------------------------------------------------------

(c) 1998 Microsoft Corporation. All rights reserved.

This document provides late-breaking or other information that supplements the Microsoft Data Link API documentation.

--------
CONTENTS
--------

1. PRODUCT DESCRIPTION
   
2. NEW FEATURES
   
3. TECHNICAL NOTES

4. KNOWN BUGS, LIMITATIONS, AND WORKAROUNDS

----------------------
1. PRODUCT DESCRIPTION
----------------------
Microsoft Data Link API provides a common user interface for defining and managing connections to OLE DB data sources. This user interface can also be called using an application programming interface, the data link API.

You can save the connection information to a data link file (.udl).  Then, you can modify these files through the Data Links Property page, and applications can use them in creating connections to various OLE DB data stores. The Data Link API provides applications the ability to select, load, or save .udl files. 

The same user interface used to manage connection information in .udl files can be used by applications to gather connection information from users when doing ad-hoc connections to OLE DB data stores. The data links API allows applications to obtain a string version of the connection information from an existing OLE DB datasource object, create a datasource object from an existing connection string, or use the Data Links dialog to edit the connection properties of an uninitialized OLE DB data source object.

---------------
2. NEW FEATURES
---------------
Microsoft Data Link API is a new feature of the MDAC 2.0 Core Components.

------------------
3. TECHNICAL NOTES
------------------

Changes from Pre-release version
--------------------------------
Several things have changed since the pre-release version of Data Link API included in the Visual Studio 98 beta 2 release. Be sure to uninstall (including unregistering) any pre-release versions of Data Link API before installing the release version.

* File Extension Change From Pre-release version
If you have used a pre-release version of the service components, the file extension of the file used to store data links has been changed to ".udl".

* File format change from Pre-release version
The file format of the data link file has been changed in the final release to support unicode. This change means that your existing pre-release data link files will not work with the final build. You will need to rebuild your data link files.  

* Argument Change from Pre-release version
The pre-release version of the IDBPromptInitialize interface supported by the data link component did not include a pointer to a controlling unknown as the first argument to PromptDataSource. Applications that call the IDBPromptInitialize::PromptInitialize method in the pre-release version of Data Link API will have to add this argument and recompile in order to work with the release version.

-------------------------------------------
4. KNOWN BUGS, LIMITATIONS, AND WORKAROUNDS
-------------------------------------------
The following is a list of Microsoft Data Link API 2.0 known issues.

* Doc Bug: Under the section "Listing Keywords Multiple Times" it states that the exception is that if the Provider keyword is listed multiple times it will use the first occurrence. This is incorrect. If the Provider keyword is listed multiple times, the last Provider keyword will be used.

* Doc Bug: Under "OLE DB Initialization Properties: Quick Reference" these additional descriptions and short values can be added:

	DBPROP_INIT_OLEDBSERVICES
	Description: OLE DB Services
	OLE DB Documented Value		Connection String Short Value
	-----------------------		-----------------------------
	DBPROPVAL_OS_RESOURCEPOOLING	ResourcePooling
	DBPROPVAL_OS_TXNENLISTMENT	TxnEnlistment
	DBPROPVAL_OS_ENABLEALL		EnableAll

* Doc Bug: In the description of IDataInitialize::GetDatasource, the fourth paragraph under the description of the ppDatasource argument should read as follows:

If *ppDataSource is non-null and no provider is specified in pwszInitializationString, then the data source specified by *ppDatasource will be used.

The word "no" is missing from the documentation.

* Doc Bug: The description of IDBPromptInitialize::PromptDatasource states that the method returns a connection string. In fact, the method returns a datasource object with the specified properties set.

* Doc Bug: The documentation states that the cSourceTypeFilter, rgSourceTypeFilter, and pwszszzProviderFilter arguments of IDBPromptInitialize::PromptDataSource are reserved for future use.  These arguments are implemented as described in the OLE DB 2.0 release.

* Doc Bug: The description of IDBPromptInitialize::PromptFileName suggests that the filename can be passed to IDataInitialze in order to get a data source object based on the connection string. This is not supported. In order to load a data source from a .udl file, the application must call IDataInitialize::LoadStringFromStorage to obtain the connection string from the file, then call IDataInitialize::GetDatasource with that string in order to obtain the data source object based on the connection string.

* Doc Bug: The description of the dwPromptOptions argument in IDBPromptInitialize::PromptFilename suggests that specifying DBPROMPTOPTIONS_NODIRECTORYCHANGE prevents the user from changing directories. In fact, there is no way to prohibit the user from changing directories while in the dialog, but if this flag is set the directory selected by the user is not set as the default directory the next time a windows file dialog is presented.

2.0 Limitation: Note that the 2.0 release of Data Link API does not support creating remote providers. Calling IDataInitialize::CreateDBInstanceEx for anything other than a local provider will fail.